From 6d969d1026959d72f707638f86e174e7caece6ba Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 9 May 2020 20:01:21 -0400 Subject: [PATCH] Update the docs Remove various references to gtk_widget_destroy in the docs. --- docs/reference/gtk/getting_started.xml.in | 13 +++++++------ docs/reference/gtk/question_index.xml | 15 ++++----------- gtk/gtkbuilder.c | 4 ++-- gtk/gtkcontainer.c | 6 ++---- gtk/gtkwidget.c | 2 +- 5 files changed, 16 insertions(+), 24 deletions(-) diff --git a/docs/reference/gtk/getting_started.xml.in b/docs/reference/gtk/getting_started.xml.in index 758b4f0d9d..d8e638f6e1 100644 --- a/docs/reference/gtk/getting_started.xml.in +++ b/docs/reference/gtk/getting_started.xml.in @@ -194,12 +194,13 @@ a g_signal_connect() with the difference lying in how the callback function is treated. g_signal_connect_swapped() allows you to specify what the callback function should take as parameter by letting you pass it as data. In this case - the function being called back is gtk_widget_destroy() and the - window pointer is passed to it. This has the effect that when - the button is clicked, the whole GTK window is destroyed. In contrast, if a normal - g_signal_connect() were used to connect the "clicked" signal with - gtk_widget_destroy(), then the button itself would have been - destroyed, not the window. More information about creating buttons can be found + the function being called back is gtk_window_destroy() and the window + pointer is passed to it. This has the effect that when the button is clicked, + the whole GTK window is destroyed. In contrast if a normal g_signal_connect() were used + to connect the "clicked" signal with gtk_window_destroy(), then the function + would be called on button (which would not go well, since + the function expects a GtkWindow as argument). + More information about creating buttons can be found here. diff --git a/docs/reference/gtk/question_index.xml b/docs/reference/gtk/question_index.xml index 0cd8062185..3353b754f0 100644 --- a/docs/reference/gtk/question_index.xml +++ b/docs/reference/gtk/question_index.xml @@ -123,8 +123,8 @@ after creating it ? If GtkFoo isn't a toplevel window, then - foo = gtk_foo_new (); - gtk_widget_destroy (foo); + foo = gtk_foo_new (); + g_object_unref (foo); is a memory leak, because no one assumed the initial floating reference. If you are using a widget and you aren't immediately @@ -137,19 +137,12 @@ To get this, you must acquire a reference to the widget and drop the floating reference (ref and sink in GTK parlance) after creating it: - foo = gtk_foo_new (); + foo = gtk_foo_new (); g_object_ref_sink (foo); -When you want to get rid of the widget, you must call gtk_widget_destroy() -to break any external connections to the widget before dropping your -reference: - - gtk_widget_destroy (foo); - g_object_unref (foo); - When you immediately add a widget to a container, it takes care of assuming the initial floating reference and you don't have to worry -about reference counting at all ... just call gtk_widget_destroy() +about reference counting at all ... just call gtk_container_remove() to get rid of the widget. diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index a4351bade1..803180c65f 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -39,14 +39,14 @@ * and drops these references when it is finalized. This finalization can * cause the destruction of non-widget objects or widgets which are not * contained in a toplevel window. For toplevel windows constructed by a - * builder, it is the responsibility of the user to call gtk_widget_destroy() + * builder, it is the responsibility of the user to call gtk_window_destroy() * to get rid of them and all the widgets they contain. * * The functions gtk_builder_get_object() and gtk_builder_get_objects() * can be used to access the widgets in the interface by the names assigned * to them inside the UI description. Toplevel windows returned by these * functions will stay around until the user explicitly destroys them - * with gtk_widget_destroy(). Other widgets will either be part of a + * with gtk_window_destroy(). Other widgets will either be part of a * larger hierarchy constructed by the builder (in which case you should * not have to worry about their lifecycle), or without a parent, in which * case they have to be added to some container to make use of them. diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c index 94c201a043..3d1a4b7071 100644 --- a/gtk/gtkcontainer.c +++ b/gtk/gtkcontainer.c @@ -288,14 +288,12 @@ gtk_container_add (GtkContainer *container, * @widget: a current child of @container * * Removes @widget from @container. @widget must be inside @container. + * * Note that @container will own a reference to @widget, and that this * may be the last reference held; so removing a widget from its * container can destroy that widget. If you want to use @widget * again, you need to add a reference to it before removing it from - * a container, using g_object_ref(). If you don’t want to use @widget - * again it’s usually more efficient to simply destroy it directly - * using gtk_widget_destroy() since this will remove it from the - * container and help break any circular reference count cycles. + * a container, using g_object_ref(). **/ void gtk_container_remove (GtkContainer *container, diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c index ef06f6f427..d1476d3828 100644 --- a/gtk/gtkwidget.c +++ b/gtk/gtkwidget.c @@ -7277,7 +7277,7 @@ gtk_widget_real_destroy (GtkWidget *object) FinalizeAssertion *assertion = l->data; if (!assertion->did_finalize) - g_critical ("Automated component '%s' of class '%s' did not finalize in gtk_widget_destroy(). " + g_critical ("Automated component '%s' of class '%s' did not finalize in dispose()" "Current reference count is %d", assertion->child_class->name, g_type_name (assertion->widget_type), -- 2.30.2